home *** CD-ROM | disk | FTP | other *** search
/ Game Programming in C++ - Start to Finish / GameProgrammingS.iso / developer_install / CEGUISDK-0.4.1-VC6-Native.exe / {app} / include / CEGUIRenderer.h < prev    next >
Encoding:
C/C++ Source or Header  |  2005-08-25  |  12.1 KB  |  402 lines
  1. /************************************************************************
  2.     filename:     CEGUIRenderer.h
  3.     created:    20/2/2004
  4.     author:        Paul D Turner
  5.     
  6.     purpose:    Defines interface for abstract Renderer class
  7. *************************************************************************/
  8. /*************************************************************************
  9.     Crazy Eddie's GUI System (http://www.cegui.org.uk)
  10.     Copyright (C)2004 - 2005 Paul D Turner (paul@cegui.org.uk)
  11.  
  12.     This library is free software; you can redistribute it and/or
  13.     modify it under the terms of the GNU Lesser General Public
  14.     License as published by the Free Software Foundation; either
  15.     version 2.1 of the License, or (at your option) any later version.
  16.  
  17.     This library is distributed in the hope that it will be useful,
  18.     but WITHOUT ANY WARRANTY; without even the implied warranty of
  19.     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  20.     Lesser General Public License for more details.
  21.  
  22.     You should have received a copy of the GNU Lesser General Public
  23.     License along with this library; if not, write to the Free Software
  24.     Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  25. *************************************************************************/
  26. #ifndef _CEGUIRenderer_h_
  27. #define _CEGUIRenderer_h_
  28.  
  29. #include "CEGUIBase.h"
  30. #include "CEGUIString.h"
  31. #include "CEGUIRect.h"
  32. #include "CEGUIColourRect.h"
  33. #include "CEGUIEventSet.h"
  34.  
  35.  
  36. // Start of CEGUI namespace section
  37. namespace CEGUI
  38. {
  39. /*!
  40. \brief
  41.     Enumerated type that contains the valid flags that can be to use when rendering image
  42. */
  43. enum OrientationFlags {
  44.     FlipHorizontal        = 1,    //!< Horizontal flip the image
  45.     FlipVertical        = 2,    //!< Vertical flip the image
  46.     RotateRightAngle    = 4        //!< Rotate the image anticlockwise 90 degree
  47. };
  48.  
  49. /*!
  50. \brief
  51.     Enumerated type that contains the valid diagonal-mode that specify how a quad is split into triangles when rendered with fx. a 3D API
  52. */
  53. enum QuadSplitMode
  54. {
  55.     TopLeftToBottomRight,    //!< Diagonal goes from top-left to bottom-right
  56.     BottomLeftToTopRight    //!< Diagonal goes from bottom-left to top-right
  57. };
  58.  
  59.  
  60. /*!
  61. \brief
  62.     Abstract class defining the interface for Renderer objects.
  63.  
  64.     Objects derived from Renderer are the means by which the GUI system interfaces
  65.     with specific rendering technologies.  To use a rendering system or API to draw
  66.     CEGUI imagery requires that an appropriate Renderer object be available.
  67. */
  68. class CEGUIEXPORT Renderer : public EventSet
  69. {
  70. public:
  71.     static const String EventNamespace;                //!< Namespace for global events
  72.  
  73.     /*************************************************************************
  74.         Event name constants
  75.     *************************************************************************/
  76.     /*!
  77.         event that fires when the underlying display size had changed.
  78.         
  79.         It is important that all Renderer implementers fire this properly as the
  80.         system itself subscribes to this event.
  81.     */
  82.     static const String EventDisplaySizeChanged;
  83.  
  84.  
  85.     /*************************************************************************
  86.         Abstract interface methods
  87.     *************************************************************************/
  88.     /*!
  89.     \brief
  90.         Add a quad to the rendering queue.  All clipping and other adjustments should have been made prior to calling this.
  91.  
  92.     \param dest_rect
  93.         Rect object describing the destination area (values are in pixels)
  94.  
  95.     \param z
  96.         float value specifying the z co-ordinate / z order of the quad
  97.  
  98.     \param tex
  99.         pointer to the Texture object that holds the imagery to be rendered
  100.  
  101.     \param texture_rect
  102.         Rect object holding the area of \a tex that is to be rendered (values are in texture co-ordinates).
  103.  
  104.     \param colours
  105.         ColourRect object describing the colour values that are to be applied when rendering.
  106.     
  107.     \param quad_split_mode
  108.         One of the QuadSplitMode values specifying the way quads are split into triangles
  109.  
  110.     \return
  111.         Nothing
  112.     */
  113.     virtual    void    addQuad(const Rect& dest_rect, float z, const Texture* tex, const Rect& texture_rect, const ColourRect& colours, QuadSplitMode quad_split_mode) = 0;
  114.  
  115.  
  116.     /*!
  117.     \brief
  118.         Perform final rendering for all quads that have been queued for rendering
  119.  
  120.         The contents of the rendering queue is retained and can be rendered again as required.  If the contents is not required call clearRenderList().
  121.  
  122.     \return
  123.         Nothing
  124.     */
  125.     virtual    void    doRender(void) = 0;
  126.  
  127.  
  128.     /*!
  129.     \brief
  130.         Clears all queued quads from the render queue.
  131.     
  132.     \return
  133.         Nothing
  134.     */
  135.     virtual    void    clearRenderList(void) = 0;
  136.  
  137.  
  138.     /*!
  139.     \brief
  140.         Enable or disable the queueing of quads from this point on.
  141.  
  142.         This only affects queueing.  If queueing is turned off, any calls to addQuad will cause the quad to be rendered directly.  Note that
  143.         disabling queueing will not cause currently queued quads to be rendered, nor is the queue cleared - at any time the queue can still
  144.         be drawn by calling doRender, and the list can be cleared by calling clearRenderList.  Re-enabling the queue causes subsequent quads
  145.         to be added as if queueing had never been disabled.
  146.  
  147.     \param setting
  148.         true to enable queueing, or false to disable queueing (see notes above).
  149.  
  150.     \return
  151.         Nothing
  152.     */
  153.     virtual void    setQueueingEnabled(bool setting) = 0;
  154.  
  155.  
  156.     /*!
  157.     \brief
  158.         Creates a 'null' Texture object.
  159.  
  160.     \return
  161.         a newly created Texture object.  The returned Texture object has no size or imagery associated with it, and is
  162.         generally of little or no use.
  163.     */
  164.     virtual    Texture*    createTexture(void) = 0;
  165.  
  166.  
  167.     /*!
  168.     \brief
  169.         Create a Texture object using the given image file.
  170.  
  171.     \param filename
  172.         String object that specifies the path and filename of the image file to use when creating the texture.
  173.  
  174.     \param resourceGroup
  175.         Resource group identifier to be passed to the resource provider when loading the texture file.
  176.  
  177.     \return
  178.         a newly created Texture object.  The initial contents of the texture memory is the requested image file.
  179.  
  180.     \note
  181.         Textures are always created with a size that is a power of 2.  If the file you specify is of a size that is not
  182.         a power of two, the final size will be rounded up.  Additionally, textures are always square, so the ultimate
  183.         size is governed by the larger of the width and height of the specified file.  You can check the ultimate sizes
  184.         by querying the texture after creation.
  185.     */
  186.     virtual    Texture*    createTexture(const String& filename, const String& resourceGroup) = 0;
  187.  
  188.  
  189.     /*!
  190.     \brief
  191.         Create a Texture object with the given pixel dimensions as specified by \a size.  NB: Textures are always square.
  192.  
  193.     \param size
  194.         float value that specifies the size to use for the width and height when creating the new texture.
  195.  
  196.     \return
  197.         a newly created Texture object.  The initial contents of the texture memory is undefined / random.
  198.  
  199.     \note
  200.         Textures are always created with a size that is a power of 2.  If you specify a size that is not a power of two, the final
  201.         size will be rounded up.  So if you specify a size of 1024, the texture will be (1024 x 1024), however, if you specify a size
  202.         of 1025, the texture will be (2048 x 2048).  You can check the ultimate size by querying the texture after creation.
  203.     */    
  204.     virtual    Texture*    createTexture(float size) = 0;
  205.  
  206.  
  207.     /*!
  208.     \brief
  209.         Destroy the given Texture object.
  210.  
  211.     \param texture
  212.         pointer to the Texture object to be destroyed
  213.  
  214.     \return
  215.         Nothing
  216.     */
  217.     virtual    void        destroyTexture(Texture* texture) = 0;
  218.  
  219.     
  220.     /*!
  221.     \brief
  222.         Destroy all Texture objects.
  223.  
  224.     \return
  225.         Nothing
  226.     */
  227.     virtual void        destroyAllTextures(void) = 0;
  228.  
  229.  
  230.     /*!
  231.     \brief
  232.         Return whether queueing is enabled.
  233.  
  234.     \return
  235.         true if queueing is enabled, false if queueing is disabled.
  236.     */
  237.     virtual bool    isQueueingEnabled(void) const = 0;
  238.  
  239.  
  240.     /*!
  241.     \brief
  242.         Return the current width of the display in pixels
  243.  
  244.     \return
  245.         float value equal to the current width of the display in pixels.
  246.     */
  247.     virtual float    getWidth(void) const    = 0;
  248.  
  249.  
  250.     /*!
  251.     \brief
  252.         Return the current height of the display in pixels
  253.  
  254.     \return
  255.         float value equal to the current height of the display in pixels.
  256.     */
  257.     virtual float    getHeight(void) const    = 0;
  258.  
  259.  
  260.     /*!
  261.     \brief
  262.         Return the size of the display in pixels
  263.  
  264.     \return
  265.         Size object describing the dimensions of the current display.
  266.     */
  267.     virtual Size    getSize(void) const        = 0;
  268.  
  269.  
  270.     /*!
  271.     \brief
  272.         Return a Rect describing the screen
  273.  
  274.     \return
  275.         A Rect object that describes the screen area.  Typically, the top-left values are always 0, and the size of the area described is
  276.         equal to the screen resolution.
  277.     */
  278.     virtual Rect    getRect(void) const        = 0;
  279.  
  280.  
  281.     /*!
  282.     \brief
  283.         Return the maximum texture size available
  284.  
  285.     \return
  286.         Size of the maximum supported texture in pixels (textures are always assumed to be square)
  287.     */
  288.     virtual    uint    getMaxTextureSize(void) const    = 0;
  289.  
  290.  
  291.     /*!
  292.     \brief
  293.         Return the horizontal display resolution dpi
  294.  
  295.     \return
  296.         horizontal resolution of the display in dpi.
  297.     */
  298.     virtual    uint    getHorzScreenDPI(void) const    = 0;
  299.  
  300.  
  301.     /*!
  302.     \brief
  303.         Return the vertical display resolution dpi
  304.  
  305.     \return
  306.         vertical resolution of the display in dpi.
  307.     */
  308.     virtual    uint    getVertScreenDPI(void) const    = 0;
  309.  
  310.  
  311.     /*************************************************************************
  312.         Basic stuff we provide in base class
  313.     *************************************************************************/
  314.     /*!
  315.     \brief
  316.         Reset the z co-ordinate for rendering.
  317.     
  318.     \return
  319.         Nothing
  320.     */
  321.     void    resetZValue(void)                {d_current_z = GuiZInitialValue;}
  322.  
  323.  
  324.     /*!
  325.     \brief
  326.         Update the z co-ordinate for the next major UI element (window).
  327.  
  328.     \return
  329.         Nothing
  330.     */
  331.     void    advanceZValue(void)                {d_current_z -= GuiZElementStep;}
  332.  
  333.  
  334.     /*!
  335.     \brief
  336.         return the current Z value to use (equates to layer 0 for this UI element).
  337.  
  338.     \return
  339.         float value that specifies the z co-ordinate to be used for layer 0 on the current GUI element.
  340.     */
  341.     float    getCurrentZ(void) const            {return d_current_z;}
  342.  
  343.  
  344.     /*!
  345.     \brief
  346.         return the z co-ordinate to use for the requested layer on the current GUI element.
  347.  
  348.     \param layer
  349.         Specifies the layer to return the Z co-ordinate for.  Each GUI element can use up to 10 layers, so valid inputs are 0 to 9 inclusive.
  350.         If you specify an invalid value for \a layer, results are undefined.
  351.  
  352.     \return
  353.         float value that specifies the Z co-ordinate for layer \a layer on the current GUI element.
  354.     */
  355.     float    getZLayer(uint layer) const        {return d_current_z - ((float)layer * GuiZLayerStep);}
  356.  
  357.  
  358.     /*!
  359.     \brief
  360.         Return identification string for the renderer module.  If the internal id string has not been
  361.         set by the Renderer module creator, a generic string of "Unknown renderer" will be returned.
  362.  
  363.     \return
  364.         String object holding a string that identifies the Renderer in use.
  365.     */
  366.     const String& getIdentifierString() const;
  367.  
  368.     virtual ResourceProvider* createResourceProvider(void);
  369.  
  370. protected:
  371.     /*************************************************************************
  372.         Construction and Destruction
  373.     *************************************************************************/
  374.     Renderer(void);
  375.  
  376. public:        // for luabind support
  377.     virtual ~Renderer(void);
  378.  
  379. private:
  380.     /*************************************************************************
  381.         Implementation constants
  382.     *************************************************************************/
  383.     static const float    GuiZInitialValue;        //!< Initial value to use for 'z' each frame.
  384.     static const float    GuiZElementStep;        //!< Value to step 'z' for each GUI element.
  385.     static const float    GuiZLayerStep;            //!< Value to step 'z' for each GUI layer.
  386.  
  387.  
  388.     /*************************************************************************
  389.         Implementation Data
  390.     *************************************************************************/
  391.     float    d_current_z;        //!< The current z co-ordinate value.
  392.  
  393. protected:
  394.     ResourceProvider* d_resourceProvider;      //!< Holds the pointer to the ResourceProvider object.
  395.     String d_identifierString;                 //!< String that holds some id information about the renderer.
  396. };
  397.  
  398. } // End of  CEGUI namespace section
  399.  
  400.  
  401. #endif    // end of guard _CEGUIRenderer_h_
  402.